[<<Previous Entry]
[^^Up^^]
[Next Entry>>]
[Menu]
[About The Guide]
WARNING: This document is subject to change at any time. Any changes made
will be indicated by a vertical bar (|) in column 1 of the file.
|Last update: 05/13/93
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
WHAT IS THE USERS.INF FILE
--------------------------
The USERS.INF file is an extension to the USERS file. It is generally
accessed solely by PCBoard software with third party software utilizing
the USERS.SYS file instead.
USERS.INF BRIEF OVERVIEW
------------------------
The USERS.INF file layout boasts some pretty high limits that hopefully
will take the software through the next few years without major
modifications. For example, the following capabilities exist within the
file structure:
* A variable number of conferences ranging from 0 to 65495 - with the other
40 conferences being stored in the main USERS file.
* A variable sized PCBoard record which will allow for growth in the future
without causing major upgrade problems with file formats are changed.
* A variable number of installable Third Party Applications (from 0 - 65535)
providing KEYWORD access to the applications and permitting the
application to "piggy back" its user record needs onto the USERS.INF file
while allowing PCBoard software to performance the maintenance on the
file.
* Variable sized records for Third Party Applications allowing each Third
Party Application to use up only what it needs - or as much as it needs.
In essence, PCBoard will have the file layout capability for as many as
65,535 conference areas (though the software may lag behind the file
layout's capabilities for some time due to memory constraints as well as
user interface problems - but those can be dealt with later on).
It will also allow Third Party Authors to install their software (using a
PCBSM) into PCBoard's system files - that is, the Third Party Software
could actually store their own information inside of PCBoard's USERS.INF
file by telling PCBoard that they are there and how much file space they
need. This way PCBoard and its utilities would be able to help out with
maintenance of the file such as adding in new records or deleting existing
records, etc.
Additionally, when PCBoard opens a door it will check the name of the
door against the KEYWORD used in the TPA header to determine if the
USERS.SYS file should include a TPA record.
USERS.INF FILE LAYOUT
---------------------
NOTE: it is recommended that people access only the USERS.SYS file and not
touch the USERS.INF leaving that job up to PCBoard. However, in the case
where an application may need to globally modify the records that belong
to it in the USERS.INF file it may be necessary to know a little about the
header record and how to get to the Third Party Application records.
The file layout comes in 4 separate parts. They are:
1) A header describing PCBoard's file allocation requirements
2) A header describing each of the TPA file allocation requirements
3) The PCBoard User Record
4) Each of the TPA extensions to the PCBoard User Record
Knowing the above you can determine the total HEADER size (comprised of
parts 1 and 2 above) by calculating the size of the PCBoard header then
adding to that the size of the application header multiplied by the number
of applications.
Determining the user record size is similarly accomplished by adding the
size of PCBoard's data record together with all of the data records
specified by the application headers.
Examples of the above will be provided down below following the formal file
formats.
USERS.INF RECORD STRUCTURES
---------------------------
typedef struct {
unsigned Version; PCBoard Version Number
unsigned NumOfConf; Number of EXTENDED Conferences Allocated in File
unsigned SizeOfRec; Size of the 'static' PCBoard User Record
long SizeOfConf; Total Size of PCBoard Conference Information
unsigned NumOfApps; Number of Third Party Apps adding onto the record
long TotalRecSize; Total Record Size (PCB and all TPA components)
} hdrtype;
typedef struct {
char Name[15]; Name of Application (NULL terminated)
unsigned Version; Version Number
unsigned SizeOfRec; Size of Application Record information (0-65535)
unsigned SizeOfConfRec; Size of Conference Record information (0-65535)
char KeyWord[9]; Keyword to execute Application (NULL terminated)
long Offset; Offset in User Record where TPA record begins
} apptype;
ACCESSING THE FILE
------------------
Accessing the file comes in two steps. One is in reading the file header
which can be done upon program initialization - and the other is in
locating a specific user record.
Step 1:
Read the HEADER record to determine (1) how big the header is and (2)
how big each record is.
To determine how big the header is you multiply the number of TPA's by
the size of the Application Header record and add to that the size of
the main Header record.
Example:
HdrSize = sizeof(hdrtype)+(Hdr.NumOfApps * sizeof(apptype));
The size of each record is stored in the header itself.
Step 2:
Using the information gathered in step 1 above it's fairly easy to get to
the actual user record. For example, if you wanted to read the
information in a user record you would use the following code:
lseek(File,(RecNum-1)*TotalRecSize + HdrSize,SEEK_SET);
In other words, you would calculate the record number minus 1 and
multiply it by the total user record size as determined in step 1
and add to that the size of the header record. Moving the disk
head to this position sets you up to read the PCBoard user record.
If you wanted to skip over the PCBoard component of the user
record then you would simply add the OFFSET of the TPA record into
the equation like this:
lseek(File,(RecNum-1)*TotalRecSize + HdrSize + Offset,SEEK_SET);
RecNum will be a LONG integer stored at offset 385 in the USERS
file (i.e. bytes 385, 386, 387 and 388 comprise the RECNUM which
will be used to access the USERS.INF file).
This file layout and accessing methodology, though somewhat complicated,
gives the following benefits:
- Because the PCBoard data size is determined by a field in the header
it is therefore allowed to GROW at will - that is to say, when
PCBoard needs new fields it can add those fields into the record and
adjust the file format without breaking Third Party Software that is
already coded to read and use the USERS.INF file.
- Because the number of conferences is specified in the header the
sysop will have the ability to grow or shrink his USERS.INF file
according to his needs as he adds or removes conferences.
- Because the header also accounts for Third Party Applications and
their needs it will allow Third Party Authors to more easily install
their software into a PCBoard system and then let PCBoard take care
of adding and removing user records. This also saves storing yet
another file on disk that may be redundant in nature compared to
similar files used by similar Third Party programs.
THE PCBOARD RECORD IN THE USERS.INF FILE
----------------------------------------
It is preferable that Third Party Applications do *not* access the PCBoard
data area within the USERS.INF file if it can be avoided for the the simple
reason that PCBoard may expand on it and access to USERS.SYS is recommended
instead. However, the following information provides details as to how the
PCBoard data record is CURRENTLY formatted:
typedef struct {
char Name[25]; User Name (in case connection to USERS is lost)
long MsgsRead; Number of messages the user has read in PCBoard
long MsgsLeft; Number of messages the user has left in PCBoard
} rectype;
The above is the current format of the STATIC portion of the the PCBoard
record. The size of which is specified in the USERS.INF header field
hdrtype.SizeOfRec.
The conference record is much more difficult to access and cannot be
described by a fixed typedef structure. The following two calculations
are required before you'll be able to read the file:
ConfByteLen = (NumAreas / 8) + ((NumAreas % 8) != 0 ? 1 : 0);
if (ConfByteLen < 5)
ConfByteLen = 5;
ExtConfLen = ConfByteLen - 5;
In the conference record you will then find 5 bit map fields in the
following order:
1) Mail Waiting Flags (length is ConfByteLen bytes long)
2) Conference Sysop Flags (length is ConfByteLen bytes long)
3) Registered In Conference (length is ExtConfLen bytes long)
4) Exp. Conference Registrations (length is ExtConfLen bytes long)
5) Conference Scan Preference (length is ExtConfLen bytes long)
Note that ConfByteLen will always be at least 5. While ExtConfLen can be 0
bytes in length if the number of conferences on the system is 39 or less.
The reason is because fields 3, 4 and 5 are already contained within the
USERS file for conferences 0 thru 39.
Immediately following the above structure are the Last Message Read
pointers. The number of which can be 0 (if 39 conferences or less) or more
if there are conferences beyond 39. Each Last Message Read pointer is a
long integer.
A note on the usage of the Registered and Expired Registration flags:
PCBoard will turn the REGISTERED flag off while leaving the EXPIRED
registration flag turned on to indicate that the caller is locked out.
Examples:
Registered Expired PCBoard Shows Explanation
---------- ------- = ------------- -----------
Off Off "" Caller is not registered but
may join if the conference is
public and his security level
permits access.
On Off "R" Caller is registered in this
conference. If he expires then
he can no longer access it
unless it is public and his
security level permits access.
On On = "RX" Caller is always registered.
Off On = "L" Caller is locked out and
cannot join the conference
regardless of whether it is
public or not.
THE PCBOARD SUPPORTED ALLOCATIONS
---------------------------------
PCBoard may actually have more information in the USERS.INF than just the
information shown above. This additional information, called PCBoard
Supported Allocations (PSAs), however, is treated exactly the same as any
Third Party Allocations (TPAs) in the file.
The only difference is that PCBoard and PCBSM directly support the PSAs by
providing access to them instead of merely storing and manipulating them.
For example, the Alias Support PSA holds a caller's alias. If it is
installed, then PCBoard will keep track of the caller's alias and PCBSM will
allow you to see the alias by hitting the F2 function key a couple of times
while in the Users File Editor.
USERS.INF FILE SIZE FORMULA
---------------------------
There has been some demand for a "formula" for easily calculating the final
size of a USERS.INF file given the known quantities of 1) number of
conferences, 2) size of TPAs and 3) number of users. The following formula
can be used for that purpose:
(( (Conf - 40) * 5 ) )
(( --------------- + (Conf - 40) * 4 + (Conf * TpaDyn) ) + TpaStat ) * Users
(( 8 ) )
Conf = the number of conferences on the system
TpaDyn = the size of all dynamic TPA allocations
TpaStat = the size of all static TPA allocations
Users = the number of users in the system
An example calculation for a system with 1000 conferences and QMAIL4
installed with 2000 users would be:
(( (1000 - 40) * 5 ) )
(( --------------- + (1000 - 40) * 4 + (1000 * 1) ) + 256 ) * 2000 =
(( 8 ) )
(( (960) * 5 ) )
(( --------- + (960) * 4 + 1000 ) + 256 ) * 2000 =
(( 8 ) )
(( 4800 ) )
(( ----- + 3840 + 1000 ) + 256 ) * 2000 =
(( 8 ) )
( 600 + 3840 + 1000 + 256 ) * 2000 =
5696 * 2000 =
11,392,000 (plus a small amount of overhead for TPA headers and such)
That's a fairly large file but for 1000 conferences and 2000 users it's
quite understandable. Smaller numbers of users and/or conferences will
yield much smaller figures. Of all of the allocations the biggest one is
the Last Message Read pointers which are 4 bytes in size for every
conference. Given the above example the LMR pointers make up 3840 bytes of
the total 5696 bytes per user.
This page created by ng2html v1.05, the Norton guide to HTML conversion utility.
Written by Dave Pearson